@YOMXXX 你好，想麻烦你帮忙 review 一下这个 re-scope 后的小 PR。

背景：原 #321 想一次性覆盖 #120 的缓存问题，体量偏大（2464 行），早期方案里 stable_wrapper 的核心假设经 feedback 后发现站不住——前缀匹配缓存是对完整前缀 token 序列做哈希，wrapper 内部动态记忆每轮变化就会让其后缓存整体失效，固定开标签对真实命中率几乎没有贡献。所以我们把 #321 拆小、并放弃了 stable_wrapper。

本 PR 只做一件事：把稳定的 persona 移到 CACHE_BOUNDARY 之前参与缓存。#375 已被定为 canonical runtime fix（解决动态 L1 的位置），两者正交、不冲突，本 PR 可作为其补充而非替代。默认 none 零行为变更。

想请确认的点：

1. prependSystemAddition 这个字段的放置方式是否符合宿主约定；
2. 这个最小方向是否值得合入，还是更希望我们直接在 fix(recall): stabilize prompt-cache memory injection #375 之上提 follow-up。

关于量化数据：#433 用的是真实 provider 实测（2 provider × 2 variant × 2 repeat × 3 turn），我们早期的自建基准是仿真、不够严谨，已不纳入本 PR；如需量化佐证，我们会参考 #433 的方法补真实测量，而不是用仿真数字。

谢谢，听你的建议。

补一个独立的缓存记账基准测试作为佐证：#450。

说明：那是确定性仿真（不调 API、不测真实 cache_read），只验证 split_system 确实把稳定 persona 移进了缓存边界前的可缓存前缀、且动态 L1 不进前缀。真实命中率数字以 #433 的 provider 实测为准，本测试不自称测得真实提升。

嗯嗯好的，我们已经收到您的PR，针对参加犀牛鸟活动的PR，我们内部近期将会排期进行集中reveiw，感谢您的关注！

补充：prependSystemContext 的 SDK 契约与消费路径证据

以下是 OpenClaw SDK 源码中的三处关键证据，证明 prependSystemContext 是官方 hook 返回契约，且被 Host 端实际消费、落在缓存边界之前。

图1：SDK 类型定义 — PluginHookBeforePromptBuildResult.prependSystemContext

文件：openclaw/src/plugins/hook-before-agent-start.types.ts

要点：prependSystemContext 是 PluginHookBeforePromptBuildResult 的正式字段，SDK 注释明确说明其用途是 "Prepended to the agent system prompt so providers can cache it"。PLUGIN_PROMPT_MUTATION_RESULT_FIELDS 数组将其列为合法 mutation 字段，确保不会被 SDK 运行时过滤。

图2：Host 端消费 — composeSystemPromptWithHookContext 函数

文件：openclaw/src/agents/embedded-agent-runner/run/attempt.thread-helpers.ts

要点：Host 端的 composeSystemPromptWithHookContext 明确接收 prependSystemContext 参数，通过 normalizeStructuredPromptSection 处理后，将其拼接到 baseSystemPrompt 之前（[prependSystem, baseSystemPrompt, appendSystem]）。这意味着 prependSystemContext 返回的内容必定落在系统提示的最前端，也就是缓存可命中前缀（cacheable prefix）中。

图3：缓存边界验证 — 官方回归测试 attempt.media-hint-cache-boundary.test.ts

文件：openclaw/src/agents/embedded-agent-runner/run/attempt.media-hint-cache-boundary.test.ts

要点：这是 OpenClaw 官方为 issue #85203 编写的回归测试，注释直接说明了 hook prependSystemContext stays in the cacheable prefix——这正是本 PR 的核心机制。而动态内容（如 media task hints）通过 prependSystemPromptAddition（非 hook 字段）被路由到缓存边界之下。这验证了我们的设计：静态 persona 通过 prependSystemContext 进入可缓存前缀，动态内容绝不混入。

与代码改动的对应关系

测试覆盖

本次提交新增 12 个测试，覆盖：

• 6 个 host-adapter 集成测试（host-adapter-integration.test.ts）：模拟 OpenClaw host 端 prompt 组装，断言 prependSystemContext 在 CACHE_BOUNDARY 之前，动态内容（L1 memories、appendSystemContext）在 CACHE_BOUNDARY 之后，3-turn 缓存前缀字节一致。
• 6 个缓存验证测试（phase2-cache-verification.test.ts）：split_system 模式可缓存前缀 167 chars vs none 模式 0 chars，动态内容零泄漏，3-turn persona 稳定性 100%。

全部 90 个测试通过（78 原有 + 12 新增）。

如需进一步验证，可在本地 OpenClaw 启用 cacheOptimization: "split_system" 后检查运行日志中 prependSystemContext= 输出即可。

宿主契约验证更新：prependSystemContext 是 OpenClaw 一等 hook 字段

以下是永久可访问的引用（替代之前可能失效的截图）：

证据 1：OpenClaw 官方文档

来源：https://docs.openclaw.ai/concepts/agent-loop

before_prompt_build hook 可返回四个字段：

• prependContext — 每轮动态文本
• systemPrompt — 覆盖系统提示
• prependSystemContext — 稳定指导，属于 system prompt 空间
• appendSystemContext — 同上

官方文档描述："Use prependContext for per-turn dynamic text and the system-context fields for stable guidance that belongs in system prompt space."

证据 2：Host 端消费路径（OpenClaw 源码解读）

来源：https://juejin.cn/post/7617692680529707034

// attempt.ts — resolvePromptBuildHookResult 后
if (hookResult?.prependSystemContext || hookResult?.appendSystemContext) {
  applySystemPromptOverrideToSession(activeSession, composedSystemPrompt);
}

Host 端显式检查并消费 prependSystemContext，将其注入 system prompt。

证据 3：#375 不覆盖 persona 位置

#375 代码：src/adapters/openclaw/recall-injection.ts

// #375 的 shapeOpenClawRecallResult 只移动 prependContext（L1 记忆）
// appendSystemContext（含 persona）完全不动：
const { prependContext, ...rest } = result;
return {
  ...rest,                              // appendSystemContext 原样 → persona 仍在边界后
  appendContext: prependContext,         // 只有 L1 记忆被移动
};

#375 的测试也证实：appendSystemContext: "<user-persona>stable</user-persona>" 在 shape 后完全不变。

结论：#375 解决 Issue #120 的主因（L1 prependContext 膨胀），#449 解决次因（persona 在 CACHE_BOUNDARY 之后）。两者正交、互补。

验证方法

无需截图。可在本地 OpenClaw 启用 persona 后检查日志：

[memory-tdai] [cache-diagnostics] prependSystemContext: ...

或在 before_prompt_build hook 返回的 prependSystemContext 字段中验证 persona 内容。